---
title: Upgrade from v2 to v3
order: 2
subGroup: upgrade-guides
---

# Upgrade from v2 to v3

## Upgrade package versions

Upgrade these package versions:

```json
{
  "devDependencies": {
    "@vitejs/plugin-react": "^2.0.1",
    "vite": "^3.0.7",
    "vite-plugin-mdx": "^3.5.6",
    "vite-plugin-react-pages": "^3.2.1",
    "vite-pages-theme-basic": "^3.0.0"
  }
}
```

Notice that you need to [migrate your app to Vite v3](https://vitejs.dev/guide/migration.html) with this setup.

It is very recommended to migrate `vite-pages-theme-basic` to [vite-pages-theme-doc](/official-theme).

### Stick with Vite v2

If you are not ready for Vite v3 for some reason, you can stick with Vite v2:

```json
{
  "devDependencies": {
    "@vitejs/plugin-react": "^1.1.4",
    "vite": "^2.5.6",
    "vite-plugin-mdx": "^3.5.6",
    "vite-plugin-react-pages": "^3.2.1",
    "vite-pages-theme-basic": "^3.0.0"
  }
}
```

Notice the version of `@vitejs/plugin-react` needs to be changed together with `vite`.

We also recommend you migrate `vite-pages-theme-basic` to [vite-pages-theme-doc](/official-theme) with this setup (with Vite v2).

## Install peerDependencies for MDX

`vite-plugin-mdx` no longer installs mdx-related peerDependencies for you. You should install them in your project:

```json
{
  "devDependencies": {
    "@mdx-js/mdx": "^1.6.22",
    "@mdx-js/react": "^1.6.22"
  }
}
```

> [vite-plugin-mdx](https://github.com/brillout/vite-plugin-mdx) has been moved to a separate repo. ([related issue](https://github.com/vitejs/vite-plugin-react-pages/issues/6))

## A Small update to theme API

> **If you have only used the basic theme and haven't created a custom theme. You don't need to care about this API change.**

In `vite-plugin-react-pages@3.x`, vite-pages don't pass staticData to the theme component anymore. You should use the hook `useStaticData` to get staticData. This API update is for less prop drilling and more efficient HMR update during dev.

```ts
interface ThemeProps {
  // staticData is removed, use useStaticData instead
  readonly loadedData: PagesLoaded
  readonly loadState: LoadState
}

/**
 * A react hook to get static data.
 * import { useStaticData } from 'vite-plugin-react-pages/client'
 */
export interface UseStaticData {
  (): PagesStaticData
  (path: string): Record<string, any>
}
```

Here is an [example upgrade commit](https://github.com/vitejs/vite-plugin-react-pages/commit/61f0fa0223ef28c526dfc7bd87bafd8de2523c38#diff-e18e1392eaf0be6f307cc5ba266f589b1517c4d991d6e0d5006c339fbe4b7ff6).

## findPages API change

> **If you have only used the "Basic Filesystem Routing Convention" and haven't used `findPages` to do "Advanced Filesystem Routing". You don't need to care about this API change.**

Previously, `vite-plugin-react-pages` don't react to the change from the fileSystem. If there is file add/update/unlink that will result in different pageData, you need to restart the dev server.
In `vite-plugin-react-pages@3.x`, vite-pages use chokidar to scan the fileSystem and watch for files.

> Thanks [Alec Larson](https://github.com/aleclarson) for the idea and initial implementation.

In order to handle the change from the fileSystem, the "Advanced Filesystem Routing" API has changed from the `findPages` API to the `pageStrategy` API. Checkout [the advanced-fs-routing doc](/advanced-fs-routing) to learn about the latest API.
